Custom Event Types (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 10 - Extending OpenDoc

Custom Event Types
You can extend OpenDoc's event-dispatching architecture to include new kinds of events by creating your own dispatch module.

Creating a Dispatch Module
The class ODDispatchModule is an abstract superclass. OpenDoc uses instances of a subclass of ODDispatchModule to dispatch certain types of events (such as keystroke events) to part editors. For normal program execution, you do not need to subclass ODDispatchModule or even access the existing dispatch module objects directly. Your interaction with OpenDoc regarding event dispatching is mainly through the dispatcher.
You can, however, provide for dispatching of new types of events or messages to your part editor by subclassing ODDispatchModule. For example, you could create a dispatch module to handle events from an exotic input device such as a 3D glove for a virtual reality game.

Patching the dispatcher
It is possible to use custom dispatch modules to patch the functioning of the dispatcher in relation to all event types, although that practice is in general not recommended. In most cases there is no need for such drastic alteration of OpenDoc functionality.
At runtime, the dispatcher maintains a dictionary of installed dispatch modules, keyed by event type. When the dispatcher's Dispatch method is called, it looks up the dispatch module for the supplied event type and calls
the Dispatch method of that module.
When the standard OpenDoc dispatch module transforms an event of one type (such as a mouse-down event in the menu bar) into an event of another type (such as an OpenDoc menu event), it passes the event back to the dispatcher for redispatching, by calling the dispatcher's Redispatch method. This redispatching allows your custom dispatch module to patch out or monitor the standard dispatch module for just those transformed events.
If you subclass ODDispatchModule, you need to implement a SOM constructor (somInit), a SOM destructor (somUninit), and an initialization method. Your initialization method should call (but not override) the InitDispatchModule method of ODDispatchModule.
Your dispatch module is responsible for actually dispatching events. The dispatcher calls your module's override of the Dispatch method, passing it the event information.
You install the dispatch module by calling the AddDispatchModule method
of the dispatcher; you remove a dispatch module by calling the RemoveDispatchModule method of the dispatcher. The installation might occur during the initialization of your part (or shell plug-in, if you create one).

Using a Dispatch Module as a Monitor
You can also install a dispatch module as a monitor. In this case, the dispatch module is notified of events of its kinds but does not have to dispatch them. You might use a monitor in a debugging tool, for example, to capture all events and display a log of the events in a window.
You install a monitor with the dispatcher's AddMonitor method. For a given event, the dispatcher calls the Dispatch method for all installed monitors (of that event type) before calling the Dispatch method of the regular dispatch module for that event type. The dispatcher ignores the Boolean function result of the Dispatch method of all monitors; therefore, unlike with normal use of a dispatch module, you can have more than one monitor for a single event type.